Turn on more accessible mode
Skip Ribbon Commands
Skip to main content
Getting Started With IceLib Statistics

​​Resources

Statistics Overview

The ININ.IceLib.Statistics namespace does not include an API element for each available statistic. Instead, it is "metadata based", where the catalog of available statistics can be retrieved from the IC server through IceLib's statistics API. The statistics catalog contains the display name, description, type, units, required statistic parameters (if any), etc. for each available statistic.

The statistics catalog is organized into "categories" of statistics. The statistics within a given category tend to represent similar concepts or areas of the IC system. They also tend to have similar parameters. A given category is often restricted by licensing, which is indicated in a security note in each section.

Understanding IceLib Statistics Classes

Classes to Define Statis​tics

The following classes are the core classes needed to define statistics in CIC. See the full ININ.IceLib.Statistics namespace documentation for further details.

StatisticsMan​ager

The StatisticsManager​ class is the manager that is needed as the root for all IceLib statistics operations. This class follows the same pattern as other IceLib namespaces, allowing the user to retrieve the instance of the class via the static method StatisticsManager.GetInstance().

Statistic​Catalog

The StatisticCatalog class, as defined by the documentation is the "gateway to the definitions of available IC statistics". This class provides access to objects that define the available statistics .
  • StatisticCategory objects via GetStatisticCategories()
  • StatisticDefinition objects via GetStatisticDefinitions()
  • ParameterType objects via GetParameterTypes()

Statisti​cCate​​gory

A StatisticCategory defines a group of statistics. These are the same as the categories defined in the Statistics Catalog. Some examples of categories are Agent Statistics and Workgroup Statistics. Using categories is not required to retrieve statistics, but it is often useful for UI display purposes. Additionally, StatisticCategory.Licenses can be used in conjunction with the information from UserConfiguration.License to pre-validate the user's ability to access a given statistics category.

StatisticDe​​finition

StatisticDefinition objects define the statistics that can be retrieved in the system. Each definition is most basically identified by the statistic ID (StatisticDefinition.Id), which is a simple URI (e.g. inin.agent:AverageTalkTime or inin.workgroup:LongestWaitTime). Each definition contains various properties to describe the statistic. For example, the properties LowerBoundValue and UpperBoundValue provide the minimum and maximum values for the statistic. The Units property describes the unit type for the statistic (e.g. seconds, kilobytes, percent, etc.). The ValueType parameter describes the data type of the statistic value (e.g. Int, String, TimeStamp, etc.).

Note that the StatisticDefinition object does not provide the value for the statistic; the real-time value ultimately comes from a StatisticValue object.

ParameterType a​nd ParameterTypeId

The ParameterType class is used to describe the parameters for a StatisticDefinition. In addition to the Id of the parameter, this class provides the DisplayText property, which is a human-friendly description of the parameter, and the PreserveOrder property, which is a boolean indicating if the order of the parameter is required to be maintained. Instances of ParameterType are retrieved from the StatisticCatalog object via GetParameterTypes() if you want a full list, or GetParameterType(ParameterTypeId) to retrieve a specific ParameterType object.

The ParameterTypeId class is similar, but only contains the Id of the parameter.

Typically, when dynamically retrieving statistics, you would use the StatisticDefinition.RequiredParameters property to get a RequiredParametersDefinition object. When enumerated, the RequiredParametersDefinition object provides a collection of ParameterTypeId objects. You would then make a request to StatisticCatalog.GetParameterType(ParameterTypeId) to get the ParameterType for each ParameterTypeId in the list. For bulk operations, it will typically be more efficient to use StatisticCatalog.GetParameterTypes() to get (and cache in your app) a full list of ParameterType objects and then use Linq to retrieve the desired ParameterType object from the collection by its Id (ParameterTypeId.Id.Id == ParameterType.Id).

Classes to Retrieve S​tatistic Values

The following classes are used to retrieve actual values for statistics.

Statistic​Listener

The StatisticListener class is the entry point for watching and retrieving statistics. The call to StartWatching(StatisticKey[]) must contain the StatisticKey objects that will be watched. Watching enables you to recieve events when a statistic changes via the StatisticValueUpdated event and also retrieve the value of the statistic at any time using the Item indexer property (StatisticListener.Item[StatisticKey]).

StatisticKey

The StatisticKey class is used to define the statistic you wish to retrieve. It differs from a StatisticDefinition in that a StatisticKey contains the parameter values that will allow the system to retrieve the StatisticValue for that specific statistic.

The StatisticKey class is always constructed by the user by providing the StatisticIdentifier and a collection of parameter values. The StatisticIdentifier will typically come from StatisticDefinition.Id. The ParameterValueKeyedCollection is constructed by the user by adding ParameterValue objects retrieved from the ParameterValuesDepot. Once the StatisticKey object has been constructed, it can be used with the StatisticListener to start watching and to retrieve the StatisticValue from StatisticListener.Items[StatisticKey].

ParameterValuesDepot​

The ParameterValuesDepot class allows the user to query for the values that can be used for a given parameter. The ExecuteQuery(ParameterQuery) method is used to retrieve the values. The returned ParameterQueryResult object contains a Values property, which is a collection of DetailedParameterValue objects. The DetailedParameterValue objects each represent one possible value that can be used when creating the StatisticKey.

StatisticValue

The StatisticValue class represents the value of a statistic returned from the CIC server. This base class has properties to provide general information about the value, but not the value itself (the value comes from the subclasses). For example, the IsNull property indicates if the CIC server actually has a value for the statistic (will be null if no data exists for the statistic) and the Definition property provides easy access to the StatisticDefinition that is related to the value.

This class has many subtypes that must be used by the application to get the value of the statistic. Each subtype has a Value property that returns the value in the correct type for the statistic (e.g. StatisticIntValue.Value is an int type and StatisticTimeStampValue.Value returns a DateTime type).

​​​​​